BBS Toolkit/BBS Toolkit.iso/doors_2/valen102.zip/SYSOP.DOC

Text File | 1993-03-16 | 29KB | 622 lines

                                  Valence
                          QWK Door for Searchlight
                                version 1.02

                             by William McBrine
                   Copyright (c) 1993 Iconoclast Software

            Written using the Searchlight Programmer's Libarary
              Portions Copyright (c) 1992 Searchlight Software


:::: INTRODUCTION ::::

This program is my own dream QWK door. There are no compromises or half-
measures anywhere in it. It doesn't compromise the QWK format, and it
doesn't compromise Searchlight's features. You get full support of such
features as included files, color codes, and metacharacters, as well as such
basics as Bulletins and Welcome, News, and Goodbye files. Plus, the setup is
both extremely simple and extremely flexible, making use of Squish's
COMPRESS.CFG for archivers, and Searchlight's own definitions for protocols.
And the program has so far proven to be very fast and very reliable.

I won't give you an intro to the idea of the QWK format or offline reading
here; by now, I assume that if you're reading this, you know what it's
about. (If not, you may find more info in VALENCE.DOC.) You may also know
something of the less-than-illustrious history of offline reading with
Searchlight. Those days are past. Offline reading should be simpler, easier,
and MORE FUN than online reading, not less. Not to brag, but with Valence, I
believe Searchlight has finally reached that point.

I first started planning this program last summer, and did some of the code
then and sporadically since, but most of it has been written in the past
month. For speed and compactness, much of the program is written in
assembly, and I intend to convert even more of it to assembly. The rest is
written in Turbo Pascal 6.0. (I'd like to complement Borland for having an
assembler built into their Pascal compiler that's easier to use than bloody
MASM.) Valence makes extensive use of the SLTPUs, and I modified the index
number conversion routine (which comprises maybe sixteen bytes out of the
whole program) from one printed in Patrick Y. Lee's text file on the QWK
format, and credited to Greg Hewgill (with a question mark). The rest is
entirely by me, from scratch. It was quite a lot of scratching, too.

I use this program every day myself. Indeed, while writing it I sometimes
found it hard to tear myself away from reading messages to actually work on
the program. What can I say - I'm a message addict. :-)

Valence should work with all versions of Searchlight from 2.15C through 3.0
(and beyond), but it has only been tested with 2.25D, 2.25 Demo, and 3.0
beta. I've tried to iron out all the bugs, and it seems quite reliable to
me, but of course I assume NO reponsibility if it annihilates your board.
:-)


:::: LICENSE DISAGREEMENT ::::

Among the many great features of Valence, the best one may be its price:
$0.00.

You are hereby authorized to make as many copies of this program as you
like, and use it on as many machines simultaneously as you like, forever,
without paying me anything, as long as you're not making any money off of
it. Commercial use requires a license (which I'll worry about when it comes
up). This program may be freely distributed throughout the universe,
provided you charge no more than a minimal copying fee (say, $5.00).
Distribution of the program at profit, or bundled with commerical software,
requires a license.

*** Why free? ***

Because I'm a programmer, not a businessman. I have no interest in that
stuff, and really just can't be bothered. Because I hate all registration
"incentives" and crippling, and couldn't stand to contaminate my program
with such. Because I don't want to be subject to the harassment I've
witnessed recently of authors who didn't "deliver" in a timely manner on
things such as registration keys. Because I don't want to contaminate my
program CODING registration keys. Because I did it out of love. Because I
did it for myself. Because it's too good to keep to myself. Because I'm a
Hacker.

*** However ***

Donations will be MORE THAN WELCOME!!! AS LONG AS you understand that if you
send me a donation, this is NOT a business transaction, that you are NOT
"registering", and that I am NOT being placed under any obligation to
"support" the program or you. I will be more than happy to support it, in
reality, but I will *NOT* be OBLIGATED to do so.

If I have to suggest an amount, I'll say "whatever you would've paid for
that other offline mail door you don't have to register now". :-)


:::: SETUP ::::

You'll believe me if I say the system requirements are "minimal", when I
tell you Valence was written and developed entirely on an 640k 8088, 8mhz,
with CGA monitor, one 5.25" DD and one 3.5" DD drive, and NO hard drive!!
And it runs beautifully on this system. I can even shell to ARJ (a notorious
memory hog) to archive the packets, while running under Searchlight (2.25
Demo), with a 128k ramdisk and 24k DIET driver loaded.

One thing you SHOULD have is a lot of file handles to open. At its worst,
Valence has eleven files open at once. I recommend setting FILES=xx in your
CONFIG.SYS to some ungodly number.

The setup is designed to be as simple as possible, yet allow maximum
flexibility. If you haven't yet, read the READ.ME file, and try the
INSTALL.EXE program. You can have Valence up and running on almost any
Searchlight system in seconds.

For options beyond what Install asks, please read the included VALENCE.ORG,
COMPRESS.CFG, and INTPROT.CFG files. These are the actual configuration
files used by Valence (VALENCE.ORG should be renamed VALENCE.CFG to run it),
complete with extensive comments.

Note that VALENCE.ORG, as supplied, boils down to this:

BBSID     NAKED
Sysop     William McBrine
Locale    Salisbury, NC
Phoneno   704-633-7817
Rename

To Valence, they are exactly equivalent. This is all the basic info you need
in the .CFG file, and you may never want to use more. But there are a
plethora of options there if you need them.

In the two most important and complex parts of the configuration, archivers
and protocols, I've tried to reduce the sysops' work to zero, while adding
about as much flexibility as possible.

*** Memory usage ***

Valence takes up about 130k when shelling to an archiver or protocol, and a
variable amount over 32k beyond that the rest of the time. (The amount
depends on the number of subboards you have; usually it will be very small.)
I am hoping to reduce the memory usage in future versions. For my comments
on swapping out to disk/EMS/XMS, see below under "FOR THE FUTURE".

*** Protocol configuration ***

For external protocols, the protcol engine uses Searchlight's own
definitions. If the protocols work in Searchlight, they should work in
Valence. It doesn't get much easier. For the "internal" protocols, read the
text file INTPROT.CFG, and edit it as needed.

Bidirectional protocols are supported by scanning for uploaded .REPs after
each Download. However, this feature is at present untested.

*** Archiver configuration ***

For its archiver setup, Valence turns to the brilliant "COMPRESS.CFG"
file format, as used by Squish (and, increasingly, other programs). There is
a sample COMPRESS.CFG included with Valence; if it works for you, you may
not need to worry anymore about it. You should at least check it for
protocols you don't have on your system, however. If you're using a
COMPRESS.CFG currently, you can set Valence up to use that one. See my
COMPRESS.CFG and VALENCE.ORG for details.

*** Manual setup ***

With the included INSTALL.EXE, I hope you'll never have to look at the
inside of a menu file when setting up Valence. But if you WANT to, technical
details are as follows:

Valence should be run with com support turned ON - on the menus, that means
either "Standard" or "Force Color". (Force Color is used by INSTALL.EXE.) In
a DOORS.DEF-style file, it means "1" or "2" for the first value. Next,
"Abort" should be set to NONE (0 for DOORS.DEF). Valence will recognize when
carrier is lost and recover by itself. Needless to say, write-protect should
also be off. For the directory setting (here's where it gets interesting),
DO NOT specify the path to the Valence directory! Use a "." to indicate the
current directory to Searchlight. THEN, in the "Command" field, specify the
full pathname to Valence (e.g., "C:\VALENCE\VALENCE.EXE"). Please include
the ".EXE" extension, to save yourself some loading time and memory.

Valence will read the CONFIG.SL2 file from the current directory, if
present; if not, it checks the "SLBBS" environent variable. Note that with
Valence, unlike many other programs, you DO *NOT* NEED to set this variable!
You may, if you like, but it shouldn't be needed. It finds its own data
files in the directory of the .EXE, regardless of what directory it was run
from.

When run without parameters, Valence will pop up a simple menu. When run
with a parameter, it will jump directly to one of the functions on that
menu. The recognized parameters are:

'D': dowmnload
'U': upload
'O': set options
'S': edit subboard list
'P': upload pointer files

Only the first letter is checked, and case is irrelevant. Install uses these
parameters to create a menu bar with six options on it (the sixth being
"Quit").

A sample DOORS.DEF line for Valence:

2;0;0;5;Valence QWK Door (offline mail);.;C:\VALENCE\VALENCE.EXE

You can get the same thing, with variations in access level and directory as
appropriate, by running "INSTALL D". For a sample menu entry, please run
Install and examine the .MNU it produces ("VALENCE.MNU", by default). You
can modify this as you like, just like any other .MNU. Also, you'll have to
edit the menu THAT menu is entered on if you want to set attributes for
Valence as well as access levels; at present, the Install program doesn't
ask for attributes.

*** Multiple MAIN.SUBs ***

This is a tricky one. If you're using more than one MAIN.SUB, and swapping
them, you have to kludge around it. You can either combine the subboard
lists into one file, and place it in the Valence directory, or have separate
Valence directories to correspond with each MAIN.SUB. (In the latter case,
you also need to swap menus or door lists.) If you DON'T do this, you'll get
people uploading replies to the wrong subboards.

Combining the subboard lists is, I hope, self-explanatory. But if you want
to maintain truly separate sub-BBSes, you have to use the multiple install
method. When doing this, make SURE you enter a different name than "Valence"
(the default) at the "Command name [Valence]:" prompt in Install for the
second and subsequent installations. Otherwise, the first menu will be
overwritten.

The principle to remember here is that if you have separate MAIN.SUBs,
you're essentially setting up completely different boards, and you must
treat them as such. Each separate installation of Valence should have its
own BBSID, so any packets mistakenly uploaded under the wrong MAIN.SUB will
be rejected.

You can mix and match these methods. Say you have three MAIN.SUBs:

MAIN.SUB
FIDO.SUB
ADULT.SUB

And say your board is named "My BBS". You might set up Valence twice; in the
first installation, say in directory "C:\VALENCE", you can combine MAIN.SUB
and FIDO.SUB into the file "C:\VALENCE\MAIN.SUB", and use the BBSID "MYBBS".
In the second installation, say in "C:\VAL-AD", you could use the BBSID
"MYADULT". Note you would not need a MAIN.SUB for this installation,
providing it could only be run while ADULT.SUB was active.

If you CAN'T swap menus or door lists for different MAIN.SUBs, you can have
two or more installations of Valence with fixed MAIN.SUBs in each Valence
directory accessible from the same menu or door list.

Note there's an option for users to turn off the MAIN.SUB file altogether,
which avoids the whole problem (and makes Valence work like some lesser QWK
doors). This could, however, be regarded as a security breach. My advice to
you is to have certain attributes required for access to each subboard not
on the main list. In fact, speaking generally, you're much better off
dividing your subboards with attributes than with MAIN.SUBs.


:::: BASIC OPERATION ::::

The basic operation is outlined in VALENCE.DOC, but there are a few details
which differ when you use it in local mode.

When Valence shells to an archiver or protocol, you'll see four numbers
displayed. E.g.:

265840 265632

298000 298000

(These are made up and do not reflect real values.) The bottom two are the
amount of free memory when shelling, and should both be the same (let me
know if they aren't!). You can use this for debugging. It is NOT displayed
to the remote users, only at the local console. (Neither is the display from
the archiver or protocol.) The top two numbers are the amount of free memory
and the size of the largest free block before RELEASE-ing the heap. This is
really just left over from my own debugging, but it may be useful to others
as well.

*** Local mode ***

When running Valence locally, you must either run it under Searchlight, OR,
exit Searchlight by responding "No" to the "Reset?" prompt, rather than by
pressing ALT-X at the waiting screen, and make sure you run it in the way
outlined above under "Manual Installation": from the directory of the node
you were logged in to, with the full path to VALENCE.EXE.

*** Downloads ***

Instead of invoking a protocol to send the file, Valence will simply move
the file to a directory specified in VALENCE.CFG, and will rename it with a
number appended if need be. The directory defaults to the Valence directory.
See VALENCE.ORG for details.

*** Uploads ***

Same deal here. The .REP file is read from the directory specified, or from
the Valence directory. Note that while remote users can use free-form names
(anything with the .REP extension is accepted), local users must rename
their .REPs in the form "<BBSID>.REP", if they aren't already named that.

*** Pointers ***

The pointer files MUST BE RENAMED to "<BBSID>.PTR" when used locally. When
used remotely, "<BBSID>.PT*" are accepted. Non-batch protocols will rename
the file to "<BBSID>.PTR". Since none of the three included .PT* files
actually ends in ".PTR", you'll HAVE to rename it here. .PTR files are
retrieved from the same directory as .REPs.


:::: TECHNICAL DETAILS ::::

Oh, you thought we were already into that part, eh? :-)

There is considerable semi-technical info in the files VALENCE.ORG,
COMPRESS.CFG, and INTPROT.CFG, and I refer you there for most of it.

VALENCE.EXE is compressed with LZEXE 0.91. The uncompressed size on last
compile was 110960 bytes.

*** Shelling ***

I put as much of my data as possible on the heap, and Valence discards it
when shelling. Also I've used local variables on the stack extensively - I
even put an 8k buffer on the stack in several places.

Note that when I said the memory use when shelling depends on how many
subboards you have, that doesn't mean I keep Searchlight's subboard list in
memory. The only heap data that isn't released is the user's subboard list
from the user file (see below).

On my last compile, I had 91840 bytes code, 25932 bytes data, and 16384
bytes stack. Add a few hundred bytes to that and you have the memory used
when shelling.

*** User file ***

One of the cleverist bits in Valence is the user file. This file records not
only the myriad options, but the list of subboards for each user. The
sublist is used for two things: to translate the record numbers on uploaded
.REP messages, and to hold the special attributes for each subboard (i.e.,
scan in personal-only mode or personal/all mode, enforce fido taglines,
allow high-bit characters in uploads, and the ansi/metacharacter conversion
options). Each subboard takes up 2 bytes if you have under 255 subboards on
your system, and 3 bytes if you have 255 or over. This is rounded up to the
nearest 128 bytes, and the main part of the user record is also 128 bytes.
The header for the file overall is 128 bytes.

The user file will grow along with your system; if you add subboards that
take it past the limits of the current record size, Valence will
automatically (and quickly) resize the whole file the next time it's run. It
will start out with the smallest record size that will contain the number of
subboards you have when it's first run. Thus, small systems with little
drive space are not penalized by oversized user files, but large systems
with hundreds of echos can easily be accomodated. Note the user file is only
resized up, never down.

For rapid searches, the user file is constructed as a binary tree. This is
just like Searchlight's user file, except there is no parent pointer in
Valence, only left and right. There's no parent pointer because there are no
deleted records. New users are always added to the end of the file. Removal
of users deleted from the BBS will require a separate maintenance program,
to be released later. I don't think you'll find this is a problem, though.
The maintenance program should also allow you to resize the user file down
if you've deleted subboards.

*** Errorlevels ***

There a bunch of errorlevels returned by Valence - a different one for each
error message. At present, there is nothing to check these, but perhaps they
will be useful in the future (in a QWK network environment?). Errorlevels
start at 80.

*** Limitations ***

The maximum length for a single message in QWK mode is limited to from 16 to
32k, depending on how full the output buffer is at the time the message is
processed. There is no limit in Text mode. (The theoretical maximum length
of a Searchlight message is 77 characters (76 per line, plus EOL) times 400,
or 30800 bytes. However, this does not include INCLUDEs, which (as far as I
know) can be any length.) I intend to double the size of the buffer
eventually. Note that a reader like SLMR, which limits the length of
messages to 150 lines, can't read more than 12k per message anyway.

Valence theoretically limits you to 8191 subboards. Memory usage makes the
actual limit more like 1000-2000. Let me know if this is a problem for
anybody. :-)

Oh, and you can only have two billion users, and they can only download two
billion messages before the number overflows into a negative value.


:::: WHY "VALENCE"? ::::

When I first started planning this program, last June or so, I intended to
call it "Spotlight". Then, recently, that name was preempted. :-( After
that, my second choice was "Maverick"... that kinda got preempted too. So
I'm left with a more or less random name. It has a nice sound, I think, but
it doesn't have any real meaning or signifigance. (Sorry to disappoint those
of you who were thinking, "Gee, I wonder why he called it that? Bet there's
a good story behind it." :-)) It may be changed if I think of a better one.


:::: FOR THE FUTURE ::::

The future of this program depends on you. Send me your complaints,
suggestions, and especially donations.

*** Known flaws in the present version ***

* Although the colors in the display are read from CONFIG.SL2, the colors in
  the filelist and the headers in Text mode are hard-wired. This should be
  corrected. The color scheme may also need revision (what do you think?).

* High-speed modem download time calculation is not very accurate. This MAY
  be fixed shortly for systems running 3.0+; have to wait for details on 3.0
  and see. In any case, it should not be fatal.

* Lines in uploaded messages are simply truncated if they're over 76
  characters long. I hope to add an option to wrap instead.

* The ANSI wrap is applied only to included files. Some readers (SLMR, at
  least) will rather crudely "wrap" the line at 80 characters if it goes
  over that length. If a message has color codes and replacement characters
  in it, it may be subjected to this. I may apply wrapping to regular
  message lines in the future to correct this.

* The ANSI wrap works great on pictures that fit within one screen, even
  animated ones, but messes up on scrolling pictures. I can fix this, but it
  may be more trouble than it's worth.

* In implementing Searchlight's color codes, I had to make a choice about
  "\no" ("normal"). In Searchlight, this is a different color for every
  system, but Valence will use light grey (color 7) always, which is the
  ANSI default. To do it the Searchlight way, I would have to insert a color
  code at the beginning of EVERY message, even those with no ANSI in them,
  because I'd have no way of knowing beforehand whether it was needed.
  However, the code to do it this way is already implemented, and it should
  be an option in future versions - at least for text packets, if not QWK.

* The (non-)handling of MAIN.SUB swapping is a kludge - when I designed it,
  I called it "the Tom Curtis kludge", because I did it only to kludge
  around HIS kludge of using a batch file to swap his MAIN.SUB and ADULT.SUB
  subboard lists. Since swapping the MAIN.SUBs is now a real feature of
  Searchlight, with its own internal command, I'll have to try to find a
  better way to handle it.

* Swapping out to disk/EMS/XMS - There is no swapping. There will not be any
  swapping, unless I get a machine I can test such a feature on. (640k and
  two floppies won't do it.) If you want swapping, send me a lot of money.

* Despite my best attempts to eliminate sources of lockups, the SLTPUs will
  occasionally hang on a grunged message (as will Searchlight). For this
  reason, as well as reasons of speed, I'd like to replace them with my own
  code, but first I need more info on Searchlight's internal text format.
  (Anybody that has it, shoot.)

* The .PTX files will not be recognized when uploaded using protocols that
  save in even block sizes, such as Xmodem. I only just realized this as I
  typed it into VALENCE.DOC. :-(

* Subboard attributes other than Personal and Personal/All cannot be set
  remotely, only online.

* The Install program leaves two copies of VALENCE.DOC on your disk - one to
  be sent to new users automatically, and one to be pulled up as a help file
  when users press ? on the "Valence" option, if it's allowed on that menu.
  This is a bit wasteful, as the file is 40k. You can delete the help file
  version of it if you like. (In some menus, it won't be accessible anyway.)

* It has been pointed out to me that there are cosmetic inconsistencies,
  e.g.,  the use of the term "High" in the subboard list editor, but the
  term "Last Read" in the new message scan to mean the same thing.

* There are some others that I know of which slip my mind at the moment.

*** What you'll see in future versions ***

* Carbon copies - Put a "CC: name, name, name" in your message and the
  header will automatically be duplicated to those people, just like in
  Searchlight.

* Netmail - As soon as Frank releases the information. Right now, Valence
  will recognize received netmail and put a "Netmail: x:xxx/yyy" message in
  the first line of any netmail you receive, but it will not send netmail.

* QWK networking - As soon as I get ANY info on how it works. Right now I
  have NOTHING!! If you have any text files on the subject, please send them
  my way. I think I have a solid base for QWK networking, because in testing
  I've done things like upload 500 messages in a .REP packet, without a
  hitch (it went just about as fast as the download). Much faster than
  SLMAIL, too.

* User file maintentance program - To trim VALENCE.USR. As it is, it only
  grows, never shrinks. Valence of course has no way of knowing when users
  are deleted from the BBS. The maintenance program will compensate.

* Long message split - Many readers can only handle messages up to x lines
  long, and truncate them if they go over the limit. Invariably, x is way
  less than Searchlight's max of 400 lines. I hope to be able to split long
  messages into multiple messages automatically; but this will require a
  signifigant rewrite.

* Option to tear off messages below tearlines in uploaded messages - That's
  why they're called tearlines, right? This is already coded and in fact is
  one of the first elements of Valence I wrote, but the option isn't set up
  yet.

* Running without being logged in - As it is, sysops running Valence locally
  must still be "logged in" to use the program. Also, running without being
  logged in may allow pre-packing of mail.

* %% upload - You'll be able to send a message to Valence and have it
  convert it to an included file. This will be the easiest way to post ANSI.

* MAIN.SUB files configurable by each user, twit filters configurable by
  each user - Maybe. Not a high priority, just something I thought would be
  cool.

* More error-checking - It already takes up more of the code than I like,
  but I can't have this thing crashing.

* Improved documentation - I hope. This was a RUSH job.

* More - I'll let you know as I think of it.

*** What you won't see ***

* Constant lockups
* Crippling
* Registration nags
* License agreements
* Obnoxious added taglines
* Exclusion by baud rate - I think it's mean.


:::: MY SAD STORY ::::

I've told you already that I programmed this on a dual-floppy CGA 8088. The
fact is, I have no money to upgrade. I also don't have my own board - I'd
like to, but couldn't possibly afford it - and had to do a lot of remote
testing. On a 2400 bps modem, working at 1200 half the time (see below). I
don't have many technical manuals, either, which I could really use, and
only a very limited selection of software.

Your donations can help, and if I get a better machine, it will speed up
development of Valence. (You can't imagine how long it takes to recompile
this thing... it's obscene.)


:::: WHERE TO REACH ME ::::

Netmail to WILLIAM MCBRINE at 1:379/301 - preferred method. (THANKS for this
new feature, Frank.) Please note I am NOT the sysop; send it to WILLIAM
MCBRINE!

Regular E-mail to WILLIAM MCBRINE on:

The Big Byte BBS                   704-279-2295 or 8873
Sysop: Tom Curtis                  1:379/301, 250:101/226

Official support site #1. Node 1 is HST, Node 2 is v.32bis. No mailer on
Node 2.

(Personally, due to line noise, I can't reliably connect at better than 1200
on Node 2 with my 2400 bps modem. Naturally, as fate or an angry god would
have it, I had to do the majority of my remote testing on Node 2, because
Node 1 and the board below were always busy.)

HomeBoy's Digital UnderGround BBS  704-637-2342
Sysop: Daniel Rymer                1:379/306, 250:101/756

Official support site #2. 2400 bps only.

The Chandrasekhar Limit BBS        704-637-1884
Sysop: Allan Tomkinson             1:379/307

Not a Searchlight system, but a board where I can usually be reached.

US Mail:

William McBrine III  <---- PLEASE include the "III", to distinguish me from
514 S. Jackson St.         my father!!!
Salisbury, NC 28144-5428

Also try the SL_NET echos.

Whichever method you use, please spell my name correctly. It's NOT "McBride"
nor "McBrian" nor any other variation; it's "McBrine". M-C-B-R-I-N-E. If you
mispell my name in e-mail, I will probably not receive it. I hate having to
say this, but people mess up my name all the time.


:::: OTHER THINGS ::::

I put more features in this program than I sometimes remember myself. If you
discover any omissions from the documentation (and I KNOW there are some),
please let me know.


:::: ACKNOWLEDGMENTS ::::

Thanks to Tom Curtis and Daniel Rymer for access to their systems, testing,
and encouragement. Thanks also to Tom for many of the files needed to
complete this project.

Thanks to Patrick Y. Lee (especially) and Jeffery Foy for their text files
on the QWK format. These were the entire basis for my code, apart from a
little reverse engineering of existing QWK packets. The Foy file is widely
distributed; the Lee file is about three times as long, and at least three
times as useful, if you can find it.

Thanks to Scott Dudley (?) for inventing the COMPRESS.CFG format, and my
complements on an elegant design.

Special thanks to Richard Bullock, sysop of Collaboration BBS in Los
Angeles, 213-779-3414, for first getting me (finally) using QWK in the first
place, and for many other files needed in this project. Thanks for a great
board, too, even if it is Wildcat. :-)

                                   * * *

        This program is dedicated to Madonna, my divine inspiration
          and to the memories of Isaac Asimov and Melena Weinhold